Dialog Manager Data Types

The following Dialog Manager data types are new, changed, or not recommended with Appearance Manager 1.0:

AlertStdAlertParamRec

A standard alert structure of type AlertStdAlertParamRec can be used when you call the function StandardAlert to customize the alert box. The AlertStdAlertParamRec type is available with Appearance Manager 1.0 and later.



 
struct AlertStdAlertParamRec {

    Boolean             movable;            

    Boolean             helpButton;         

    ModalFilterUPP      filterProc;          

    StringPtr           defaultText;    

    StringPtr           cancelText;         

    StringPtr           otherText;          

    SInt16              defaultButton;  

    SInt16              cancelButton;   

    UInt16              position;           

};

typedef struct AlertStdAlertParamRec AlertStdAlertParamRec;

typedef AlertStdAlertParamRec *AlertStdAlertParamPtr;

movable: A Boolean value indicating whether or not the alert box is movable.
helpButton: A Boolean value indicating whether or not the alert includes a Help button.
filterProc: If the value in the movable field is true (alert is movable), then specify in this parameter a universal procedure pointer to an application-defined filter function that responds to events not handled by ModalDialog . If you do, all events will get routed to your application-defined event filter function for handling, even when your alert box window is in the background. If you set this parameter to nil , the Dialog Manager uses the standard event filter function.
defaultText: Text for button in OK position; see Alert Default Text Constants . The button automatically sizes and positions itself in the alert box. To specify that the default button names should be used, pass -1 . To indicate that no button should be displayed, pass nil .
cancelText: Text for button in Cancel position; see Alert Default Text Constants . The button automatically sizes and positions itself in the alert box. To specify that the default button names should be used, pass -1 . To indicate that no button should be displayed, pass nil .
otherText: Text for button in leftmost position; see Alert Default Text Constants . The button automatically sizes and positions itself in the alert box. To specify that the default button names should be used, pass -1 . To indicate that no button should be displayed, pass nil .
defaultButton: Specifies which button acts as the default button; see Alert Button Constants .
cancelButton: Specifies which button acts as the Cancel button (can be 0); see Alert Button Constants .
position: The alert box position, as defined by a window positioning constant; see Macintosh Toolbox Essentials for a discussion of these constants. In this structure, the constant kWindowDefaultPosition is equivalent to the constant kWindowAlertPositionParentWindowScreen .

'DLOG'

A dialog resource is a resource of type 'DLOG' . All dialog resources can be marked purgeable, and they must have resource ID numbers greater than 127. With Appearance Manager 1.0, the 'DLOG' resource has been changed to support the dialog font table ('dftb') resource; see 'dftb' for a description of the dialog font table resource.

You can use an extended dialog resource with the same resource ID as your dialog resource to provide additional features for your dialog box, including movable modal behavior, Appearance-compliant backgrounds and controls, and embedding hierarchies. See 'dlgx' for a description of the extended dialog resource. Use the GetNewDialog function to create the dialog box defined in the dialog resource and extended dialog resource .

Figure 1-1 shows the format of a compiled dialog resource.

Figure 1-1 Structure of a compiled dialog ('DLOG') resource

The compiled version of a dialog resource contains the following elements:

Rectangle. This determines the dialog box's dimensions and, possibly, its position. (The last element in the dialog resource usually specifies a position for the dialog box.)
Window definition ID . See Mac OS 8 Window Manager Reference for descriptions of the ID constants that can be used in this field to specify Appearance-compliant modal, movable modal, or modeless dialog boxes .
Visibility. If this is set to a value of 1 (as specified by the visible constant in the Rez input file) , the Dialog Manager displays this dialog box as soon as you call the GetNewDialog function GetNewDialog . If this is set to a value of 0 (as specified by the invisible constant in the Rez input file) , the Dialog Manager does not display this dialog box until you call the Window Manager function ShowWindow .
Close box specification. This specifies whether to draw a close box. Normally, this is set to a value of 1 (as specified by the goAway constant in the Rez input file) only for a modeless dialog box to specify a close box in its title bar. Otherwise, this is set to a value of 0 (as specified by the noGoAway constant in the Rez input file ).
Reference constant. This contains any value that an application stores here. For example, an application can store a number here that represents a dialog box type, in order to distinguish between a number of similar dialog boxes. As this information is stored in a window structure within the dialog structure, you can use the Window Manager function SetWRefCon at any time to change this value in the dialog structure for a dialog box, and you can use the Window Manager function GetWRefCon to determine its current value.
Item list resource ID. This ID specifies both the item list resource and the dialog font table resource that will be used with this dialog box. See 'dftb' for a description of the dialog font table resource.
Window title. A string displayed in the dialog box's title bar only when the dialog box is modeless or movable modal.
Alignment byte. This is an extra byte added if necessary to make the previous Pascal string end on a word boundary.
Dialog box position. A constant specifying the position of the dialog box on the screen; see the discussion of window positioning constants in Macintosh Toolbox Essentials (page 4-126). If your application positions dialog boxes on its own, you shouldn't use these constants, because they may cause conflicts with the Dialog Manager.

If 0x0000 appears here (as specified by the kWindowDefaultPosition constant in the Rez input file) , the Dialog Manager positions this dialog box according to the global coordinates specified in the rectangle element of this resource.
If 0xB00A appears here (as specified by the kWindowAlertPositionParentWindow constant in the Rez input file), the Dialog Manager positions the dialog box over the frontmost window so that the window's title bar appears.
If 0x300A appears here (as specified by the kWindowAlertPositionMainScreen constant in the Rez input file), the Dialog Manager centers the dialog box near the top of the main screen.
If 0x700A appears here (as specified in the Rez input file by the kWindowAlertPositionParentWindowScreen constant), the Dialog Manager positions the dialog box on the screen where the user is currently working.

Note

Alert titles are only available with Appearance version 1.0.1 and later.

All extended alert resources can be marked purgeable, and they must have the same resource ID and resource file as their corresponding alert resource. Figure 1-3 shows the structure of a compiled extended alert resource.

Figure 1-3 Structure of a compiled extended alert ('alrx') resource

The compiled version of an extended alert resource contains the following elements:

Version number. An integer specifying the version of the format of the resource.
Alert flags. Constants specifying the alert box's Appearance features; see Alert Feature Flag Constants .
Reference constant. This contains any value that an application wishes to store here. For example, an application can store a number here that represents an alert box type, in order to distinguish between a number of similar alert boxes. As this information is stored in a window structure within the dialog structure, you can use GetWRefCon to determine this value.
Window type. If this Boolean is set to 1 (true ), the Dialog Manager specifies an Appearance-compliant window definition ID constant directly when drawing the alert box window.
Reserved. Set to 0.
Window title. A string representing the title of a movable alert box.

'dftb'

Your application can specify the initial font settings for all controls in a dialog box or alert box by creating a dialog font table resource of type 'dftb' with the same resource ID as the item list resource ( 'DITL' ). The control font style information in the dialog font table resource is automatically read in (along with the 'DITL' ) by the Dialog Manager. When the 'dftb' resource is read in, the control font styles are set, and the resource is marked purgeable.

When an embedding hierarchy is established in a dialog box, the dialog font table resource should be used instead of the item color table ( 'ictb' ) resource, since edit and static text dialog items become controls in an embedding hierarchy. The dialog font table resource is available with Appearance 1.0 and later.

Figure 1-4 shows the format of a compiled dialog font table resource.

Figure 1-4 Structure of a compiled dialog font table ('dftb') resource

A compiled version of a 'dftb' resource contains the following elements:

Version number. An integer specifying the version of the format of the resource.
Number of entries. An integer that specifies the number of entries in the resource. Each entry is a dialog control font structure.
Dialog control font entries. A series of dialog control font structures, each of which consist of type, dialog font flags, the font ID, font size, font style, text mode, justification, text color, background color, and font name.

Figure 1-5 shows the format of a compiled dialog control font entry in a 'dftb' resource.

Figure 1-5 Structure of dialog control font entry in a'dftb' resource

Each entry in a 'dftb' resource corresponds to a dialog item and contains the following elements:

Type. An integer that specifies whether there is font information for the dialog or alert item in the 'DITL' . If you specify a value of 0, there is no font information for the item in the corresponding 'DITL' , and no data follows. If you specify a value of 1, there is font information for the item, and the rest of the structure is read. You can cause entries to be skipped by setting this value to 0.
Dialog font flags. You can use one or more of these flag constants to specify which other fields in the dialog font table should be used; see Dialog Font Flag Constants .
Font ID. If the kDialogFontUseFontMask bit is set to 1, then this element will contain an integer indicating the ID of the font family to use. See Mac OS 8 Control Manager Reference for information about the metafont constants that you can specify in this field. If this bit is set to 0, then the system default font is used.
Font size. If a constant representing the system font, small system font, or small emphasized system font is specified in the Font ID field, this field is ignored. If the kDialogFontUseSizeMask bit is set, this field should contain an integer representing the point size of the text. If the kDialogFontAddSizeMask bit is set, this value will contain the size to add to the current point size of the text.
Style. If the kDialogFontUseFaceMask bit is set, then this element should contain an integer specifying the text style to describe which styles to apply to the text. You can use one or more of the following style data type mask constants to specify font style:

	Bit value	Style
	0x00	Normal
	0x01	Bold
	0x02	Italic
	0x04	Underline
	0x08	Outline
	0x10	Shadow
	0x20	Condense
	0x40	Extend

Text mode. If the kDialogFontUseModeMask bit is set, then this element should contain an integer specifying how characters are drawn. See Inside Macintosh: Imaging With QuickDraw for a discussion of source transfer modes.
Justification. If the kDialogFontUseJustMask bit is set, then this element should contain an integer specifying text justification (left, right, centered, or system-justified).
Text color. If the kDialogUseFontForeColorMask bit is set, then this element should contain a color to use when drawing the text.
Background color. If the kDialogFontUseBackColorMask bit is set, then this element should contain a color to use when drawing the background behind the text. In certain text modes, background color is ignored.
Font name. If the kDialogFontUseFontNameMask bit is set, then this element should contain a Pascal string representing the font name to be used. This overrides the font ID.

'dctb'

The dialog color table resource is not recommended with Appearance Manager 1.0 and later. When the Appearance Manager is available and the kDialogFlagsUseThemeBackground feature bit of the extended dialog resource 'DLOG' is set, the entire dialog color table resource ('dctb') is ignored. If the Appearance Manager is available, but the above is not true, the wContent field of the 'dctb' resource is used, but all other fields are still ignored.

'actb'

The alert color table resource is not recommended with Appearance Manager 1.0 and later. When the Appearance Manager is available and thekAlertFlagsUseThemeBackground feature bit of the extended alert resource is set, the entire alert color table resource ('actb') is ignored. If the Appearance Manager is available, but the kAlertFlagsUseThemeBackground bit is not set, the wContent field of the 'actb' resource is used, but all other fields are still ignored.

'ictb'

The item color table resource is not recommended with Appearance Manager 1.0 and later. When the Appearance Manager is available and an embedding hierarchy is established in the dialog box, any item color table ('ictb') resource information is ignored. The dialog font table ('dftb') resource should be used instead of the item color table resource to specify the font settings for all dialog items in an embedding hierarchy.

If an embedding hierarchy is not established, the item color table resource can be used to set the font information for any editable text and static text dialog items, but the dialog font table resource will still be used for any controls in the dialog box.